3 * Advanced generator of database load balancing objects for database farms.
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
15 * You should have received a copy of the GNU General Public License along
16 * with this program; if not, write to the Free Software Foundation, Inc.,
17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 * http://www.gnu.org/copyleft/gpl.html
24 namespace Wikimedia\Rdbms
;
26 use InvalidArgumentException
;
29 * A multi-database, multi-master factory for Wikimedia and similar installations.
30 * Ignores the old configuration globals.
34 class LBFactoryMulti
extends LBFactory
{
35 /** @var array A map of database names to section names */
36 private $sectionsByDB;
39 * @var array A 2-d map. For each section, gives a map of server names to
42 private $sectionLoads;
45 * @var array[] Server info associative array
46 * @note The host, hostName and load entries will be overridden
48 private $serverTemplate;
52 /** @var array A 3-d map giving server load ratios for each section and group */
53 private $groupLoadsBySection = [];
55 /** @var array A 3-d map giving server load ratios by DB name */
56 private $groupLoadsByDB = [];
58 /** @var array A map of hostname to IP address */
59 private $hostsByName = [];
61 /** @var array A map of external storage cluster name to server load map */
62 private $externalLoads = [];
65 * @var array A set of server info keys overriding serverTemplate for
68 private $externalTemplateOverrides;
71 * @var array A 2-d map overriding serverTemplate and
72 * externalTemplateOverrides on a server-by-server basis. Applies to both
73 * core and external storage
75 private $templateOverridesByServer;
77 /** @var array A 2-d map overriding the server info by section */
78 private $templateOverridesBySection;
80 /** @var array A 2-d map overriding the server info by external storage cluster */
81 private $templateOverridesByCluster;
83 /** @var array An override array for all master servers */
84 private $masterTemplateOverrides;
87 * @var array|bool A map of section name to read-only message. Missing or
88 * false for read/write
90 private $readOnlyBySection = [];
92 /** @var LoadBalancer[] */
93 private $mainLBs = [];
95 /** @var LoadBalancer[] */
99 private $loadMonitorClass = 'LoadMonitor';
105 private $lastSection;
108 * @see LBFactory::__construct()
110 * Template override precedence (highest => lowest):
111 * - templateOverridesByServer
112 * - masterTemplateOverrides
113 * - templateOverridesBySection/templateOverridesByCluster
114 * - externalTemplateOverrides
116 * Overrides only work on top level keys (so nested values will not be merged).
118 * Server configuration maps should be of the format Database::factory() requires.
119 * Additionally, a 'max lag' key should also be set on server maps, indicating how stale the
120 * data can be before the load balancer tries to avoid using it. The map can have 'is static'
121 * set to disable blocking replication sync checks (intended for archive servers with
124 * @param array $conf Parameters of LBFactory::__construct() as well as:
125 * - sectionsByDB Map of database names to section names.
126 * - sectionLoads 2-d map. For each section, gives a map of server names to
127 * load ratios. For example:
134 * - serverTemplate Server configuration map intended for Database::factory().
135 * Note that "host", "hostName" and "load" entries will be
136 * overridden by "sectionLoads" and "hostsByName".
137 * - groupLoadsBySection 3-d map giving server load ratios for each section/group.
147 * - groupLoadsByDB 3-d map giving server load ratios by DB name.
148 * - hostsByName Map of hostname to IP address.
149 * - externalLoads Map of external storage cluster name to server load map.
150 * - externalTemplateOverrides Set of server configuration maps overriding
151 * "serverTemplate" for external storage.
152 * - templateOverridesByServer 2-d map overriding "serverTemplate" and
153 * "externalTemplateOverrides" on a server-by-server basis.
154 * Applies to both core and external storage.
155 * - templateOverridesBySection 2-d map overriding the server configuration maps by section.
156 * - templateOverridesByCluster 2-d map overriding the server configuration maps by external
158 * - masterTemplateOverrides Server configuration map overrides for all master servers.
159 * - loadMonitorClass Name of the LoadMonitor class to always use.
160 * - readOnlyBySection A map of section name to read-only message.
161 * Missing or false for read/write.
163 public function __construct( array $conf ) {
164 parent
::__construct( $conf );
166 $required = [ 'sectionsByDB', 'sectionLoads', 'serverTemplate' ];
167 $optional = [ 'groupLoadsBySection', 'groupLoadsByDB', 'hostsByName',
168 'externalLoads', 'externalTemplateOverrides', 'templateOverridesByServer',
169 'templateOverridesByCluster', 'templateOverridesBySection', 'masterTemplateOverrides',
170 'readOnlyBySection', 'loadMonitorClass' ];
172 foreach ( $required as $key ) {
173 if ( !isset( $conf[$key] ) ) {
174 throw new InvalidArgumentException( __CLASS__
. ": $key is required." );
176 $this->$key = $conf[$key];
179 foreach ( $optional as $key ) {
180 if ( isset( $conf[$key] ) ) {
181 $this->$key = $conf[$key];
187 * @param bool|string $domain
190 private function getSectionForDomain( $domain = false ) {
191 if ( $this->lastDomain
=== $domain ) {
192 return $this->lastSection
;
194 list( $dbName, ) = $this->getDBNameAndPrefix( $domain );
195 $section = $this->sectionsByDB
[$dbName] ??
'DEFAULT';
196 $this->lastSection
= $section;
197 $this->lastDomain
= $domain;
203 * @param bool|string $domain
204 * @return LoadBalancer
206 public function newMainLB( $domain = false ) {
207 list( $dbName, ) = $this->getDBNameAndPrefix( $domain );
208 $section = $this->getSectionForDomain( $domain );
209 $groupLoads = $this->groupLoadsByDB
[$dbName] ??
[];
211 if ( isset( $this->groupLoadsBySection
[$section] ) ) {
212 $groupLoads = array_merge_recursive(
213 $groupLoads, $this->groupLoadsBySection
[$section] );
216 $readOnlyReason = $this->readOnlyReason
;
217 // Use the LB-specific read-only reason if everything isn't already read-only
218 if ( $readOnlyReason === false && isset( $this->readOnlyBySection
[$section] ) ) {
219 $readOnlyReason = $this->readOnlyBySection
[$section];
222 $template = $this->serverTemplate
;
223 if ( isset( $this->templateOverridesBySection
[$section] ) ) {
224 $template = $this->templateOverridesBySection
[$section] +
$template;
227 return $this->newLoadBalancer(
229 $this->sectionLoads
[$section],
236 * @param DatabaseDomain|string|bool $domain Domain ID, or false for the current domain
237 * @return LoadBalancer
239 public function getMainLB( $domain = false ) {
240 $section = $this->getSectionForDomain( $domain );
241 if ( !isset( $this->mainLBs
[$section] ) ) {
242 $this->mainLBs
[$section] = $this->newMainLB( $domain );
245 return $this->mainLBs
[$section];
248 public function newExternalLB( $cluster ) {
249 if ( !isset( $this->externalLoads
[$cluster] ) ) {
250 throw new InvalidArgumentException( __METHOD__
. ": Unknown cluster \"$cluster\"" );
252 $template = $this->serverTemplate
;
253 if ( $this->externalTemplateOverrides
) {
254 $template = $this->externalTemplateOverrides +
$template;
256 if ( isset( $this->templateOverridesByCluster
[$cluster] ) ) {
257 $template = $this->templateOverridesByCluster
[$cluster] +
$template;
260 return $this->newLoadBalancer(
262 $this->externalLoads
[$cluster],
264 $this->readOnlyReason
268 public function getExternalLB( $cluster ) {
269 if ( !isset( $this->extLBs
[$cluster] ) ) {
270 $this->extLBs
[$cluster] = $this->newExternalLB( $cluster );
273 return $this->extLBs
[$cluster];
276 public function getAllMainLBs() {
278 foreach ( $this->sectionsByDB
as $db => $section ) {
279 if ( !isset( $lbs[$section] ) ) {
280 $lbs[$section] = $this->getMainLB( $db );
287 public function getAllExternalLBs() {
289 foreach ( $this->externalLoads
as $cluster => $unused ) {
290 $lbs[$cluster] = $this->getExternalLB( $cluster );
297 * Make a new load balancer object based on template and load array
299 * @param array $template
300 * @param array $loads
301 * @param array $groupLoads
302 * @param string|bool $readOnlyReason
303 * @return LoadBalancer
305 private function newLoadBalancer( $template, $loads, $groupLoads, $readOnlyReason ) {
306 $lb = new LoadBalancer( array_merge(
307 $this->baseLoadBalancerParams(),
309 'servers' => $this->makeServerArray( $template, $loads, $groupLoads ),
310 'loadMonitor' => [ 'class' => $this->loadMonitorClass
],
311 'readOnlyReason' => $readOnlyReason
314 $this->initLoadBalancer( $lb );
320 * Make a server array as expected by LoadBalancer::__construct, using a template and load array
322 * @param array $template
323 * @param array $loads
324 * @param array $groupLoads
327 private function makeServerArray( $template, $loads, $groupLoads ) {
330 $groupLoadsByServer = $this->reindexGroupLoads( $groupLoads );
331 foreach ( $groupLoadsByServer as $server => $stuff ) {
332 if ( !isset( $loads[$server] ) ) {
336 foreach ( $loads as $serverName => $load ) {
337 $serverInfo = $template;
339 $serverInfo['master'] = true;
340 if ( $this->masterTemplateOverrides
) {
341 $serverInfo = $this->masterTemplateOverrides +
$serverInfo;
345 $serverInfo['replica'] = true;
347 if ( isset( $this->templateOverridesByServer
[$serverName] ) ) {
348 $serverInfo = $this->templateOverridesByServer
[$serverName] +
$serverInfo;
350 if ( isset( $groupLoadsByServer[$serverName] ) ) {
351 $serverInfo['groupLoads'] = $groupLoadsByServer[$serverName];
353 $serverInfo['host'] = $this->hostsByName
[$serverName] ??
$serverName;
354 $serverInfo['hostName'] = $serverName;
355 $serverInfo['load'] = $load;
356 $serverInfo +
= [ 'flags' => IDatabase
::DBO_DEFAULT
];
358 $servers[] = $serverInfo;
365 * Take a group load array indexed by group then server, and reindex it by server then group
366 * @param array $groupLoads
369 private function reindexGroupLoads( $groupLoads ) {
371 foreach ( $groupLoads as $group => $loads ) {
372 foreach ( $loads as $server => $load ) {
373 $reindexed[$server][$group] = $load;
381 * @param DatabaseDomain|string|bool $domain Domain ID, or false for the current domain
382 * @return array [database name, table prefix]
384 private function getDBNameAndPrefix( $domain = false ) {
385 $domain = ( $domain === false )
387 : DatabaseDomain
::newFromId( $domain );
389 return [ $domain->getDatabase(), $domain->getTablePrefix() ];
393 * Execute a function for each tracked load balancer
394 * The callback is called with the load balancer as the first parameter,
395 * and $params passed as the subsequent parameters.
396 * @param callable $callback
397 * @param array $params
399 public function forEachLB( $callback, array $params = [] ) {
400 foreach ( $this->mainLBs
as $lb ) {
401 $callback( $lb, ...$params );
403 foreach ( $this->extLBs
as $lb ) {
404 $callback( $lb, ...$params );